API de Imagen 2.1 de IIIF

Estado de este Documento

Esta Versión: 2.1.0

Última Versión Estable: 2.1.0

Versión Anterior: 2.0

Editores:

• Michael Appleby , Universidad de Yale
• Tom Crane , Digirati
• Robert Sanderson , Universidad de Stanford
• Jon Stroop , Biblioteca de la Universidad de Princeton
• Simeon Warner , Universidad de Cornell

Copyright © 2012-2017 Editores y colaboradores. Publicado por IIIF Consortium bajo la licencia CC-BY, ver aviso legal.

Tabla de Contenidos

• 1. Introducción
  • 1.1. Audiencia y Ámbito
  • 1.2. Terminología
• 2. Sintaxis de URI
  • 2.1. Sintaxis de URI de Petición de Imagen
  • 2.2. Sintaxis de URI de Petición de Información de Imagen
• 3. Identificador
• 4. Parámetros de Petición de Imagen
  • 4.1. Región
  • 4.2. Tamaño
    
  • 4.3. Rotación
  • 4.4. Calidad
  • 4.5. Formato
  • 4.6. Orden de Implementación
  • 4.7. Sintaxis de URI Canónica
• 5. Información de Imagen
  • 5.1. Petición de Información de Imagen
  • 5.2. Propiedades Técnicas
  • 5.3. Descripción de Perfil
  • 5.4. Propiedades de Derechos y Licencias
  • 5.5. Servicios Relacionados
  • 5.6. Respuesta Completa
• 6. Niveles de Cumplimiento
• 7. Respuestas de Servidor
  • 7.1. Respuestas Exitosas
  • 7.2. Condiciones de Error
• 8. Autenticación
• 9. Codificación y Decodificación de URI
• 10. Consideraciones de Seguridad
• 11. Apéndices
  • A. Notas de Implementación
  • B. Control de Versiones
  • C. Agradecimientos
  • D. Registro de Cambios

1. Introducción

Este documento describe una API de imagen definida por IIIF (pronunciado “Triple-I-Efe”) Consortium. La API de Imagen de IIIF especifica un servicio web que retorna una imagen en respuesta a una petición HTTP o HTTPS estándar. La URI puede indicar región, tamaño, rotación, características de calidad, y formato de la imagen solicitada. También es posible construir una URI para solicitar información técnica básica de la imagen a fin de soportar aplicaciones cliente. Esta API se concibió para facilitar la reutilización sistemática de recursos de imagen en repositorios de imágenes digitales mantenidos por organizaciones del patrimonio cultural. Puede ser adoptada por cualquier repositorio o servicio de imagen, y permite recuperar imágenes estáticas en respuesta a URIs construídas apropiadamente.

Por favor, envíe sus comentarios a iiif-discuss@googlegroups.com.

1.1. Audiencia y Ámbito

Este documento está destinado a arquitectos y desarrolladores de aplicaciones que comparten y consumen imágenes digitales, particularmente de instituciones del patrimonio cultural, museos, bibliotecas y archivos. Las aplicaciones previstas incluyen:

• Repositorios de imágenes digitales y redes de contenido distribuído.
• Aplicaciones web de imagen, por ejemplo, visores pan/zoom, lectores de libros, etc.
• Aplicaciones cliente que usan contenido de imagen para análisis o comparación.

Esta especificación tiene que ver con las peticiones de imagen por parte del cliente, no con la gestión de imágenes por el servidor. Describe como responder a peticiones que cumplan una sintaxis de URI particular, pero no define métodos de implementación, por ejemplo, algoritmos de rotación, transcodificación, gestión de color, compresión, o cómo responder a URIs que no cumplan la sintaxis especificada. Eso permite flexibilidad en la implementación para dominios con restricciones particulares o prácticas comunitarias específicas, al tiempo que soporta la interoperabilidad en el caso general.

1.2. Terminología

En este documento, las palabras resaltadas debe(n) y requerido(a) implican que la definición es un requisito absoluto de la especificación; la expresión no debe(n) implica que la definición es una prohibición absoluta de la especificación; las palabras debiera(n) y recomendado(a) implican que pueden existir razones válidas en circunstancias particulares para ignorar un elemento particular, pero es preciso comprender y sopesar cuidadosamente todas las consecuencias antes de seguir un curso diferente; las expresiones no debiera(n) o no recomendado(a) implican que pueden existir razones válidas en circunstancias particulares donde el comportamiento particular es aceptable o útil, pero es preciso comprender y sopesar cuidadosamente todas las consecuencias antes de implementarlo; las palabras puede(n) y opcional implican que el elemento de la especificación es verdaderamente opcional, si bien la implementación que no incluya una opción particular debe estar preparada para interoperar con otra implementación que sí la incluya (aunque quizás con funcionalidad reducida) e, inversamente, una implementación que incluya una opción particular debe estar preparada para interoperar con otra implementación que no la incluya (excepto, por supuesto, para la característica proporcionada por la opción).

2. Sintaxis de URI

La API de Imagen de IIIF se puede invocar de dos maneras:

• Solicitar una imagen, que puede ser parte de una imagen mayor.
• Solicitar información sobre la imagen, incluyendo características, funcionalidad disponible, y servicios relacionados.

Ambas transmiten la información de la petición en los segmentos de ruta de la URI, no como parámetros de consulta. Eso facilita el caching de las respuestas en el servidor o la infraestructura estándar de caching web. También permite una implementación mínima usando archivos pre-calculados en una estructura de directorios correspondiente.

Hay cuatro parámetros compartidos por las peticiones, y otras especificaciones IIIF:

La combinación de esos parámetros forma la URI base de la imagen, e identifica el contenido de imagen subyacente. Se construye de acuerdo a la siguiente Plantilla de URI (RFC6570):

{esquema}://{servidor}{/prefijo}/{identificador}

Cuando la URI base es desreferenciada, la interacción debiera producir el documento de información de imagen. Es recomendado que la respuesta sea una redirección de estado 303 a la URI del documento de información de imagen. Las implementaciones también pueden presentar otro comportamiento para la URI base, ajeno al ámbito de esta especificación, en respuesta a headers de petición HTTP y métodos.

A fin de admitir extensiones, esta especificación no define el comportamiento del servidor al recibir peticiones que no coincidan con la URI base o alguna de las sintaxis de URI descritas más adelante.

2.1. Sintaxis de URI de Petición de Imagen

La URI de la API de Imagen de IIIF para solicitar una imagen debe cumplir la siguiente Plantilla de URI:

{esquema}://{servidor}{/prefijo}/{identificador}/{región}/{tamaño}/{rotación}/{calidad}.{formato}

Por ejemplo:

http://www.example.org/image-service/abcd1234/full/full/0/default.jpg

Los parámetros de la URI de Petición de Imagen incluyen región, tamaño, rotación, calidad y formato, y definen las características de la imagen retornada. Se describen en detalle en Parámetros de Petición de Imagen.

2.2. Sintaxis de URI de Petición de Información de Imagen

La URI para solicitar información de imagen debe cumplir la siguiente Plantilla de URI:

{esquema}://{servidor}{/prefijo}/{identificador}/info.json

Por ejemplo:

http://www.example.org/image-service/abcd1234/info.json

Los componentes esquema, servidor, prefijo e identificador de la petición de información deben ser idénticos a los componentes correspondientes de la petición de imagen para el contenido de imagen descrito por el documento de información de imagen. El documento de información de imagen se explica en detalle en la sección Información de Imagen.

3. Identificador

La API no impone restricciones a la forma de los identificadores que un servidor puede usar o soportar. Los caracteres especiales (por ejemplo, ? o #) deben ser codificados URI para evitar comportamientos impredecibles de los clientes. La sintaxis de URI se basa en separadores slash (/) por lo cual todo slash del identificador debe ser codificado URI (“codificado con porciento”). Más información en Codificación y Decodificación de URI.

4. Parámetros de Petición de Imagen

Todos los parámetros descritos seguidamente son requeridos para la construcción adecuada de una URI de la API de Imagen de IIIF. La secuencia de parámetros en la URI debe tener el orden definido a continuación. El orden de los parámetros está pensado como recurso mnemotécnico para el orden de las operaciones con las cuales el servicio manipula el contenido de imagen. De esa manera, el contenido de imagen solicitado es extraído como una región de la imagen completa, escalado al tamaño solicitado, reflejado y/o rotado, y transformado a la calidad de color y formato. El contenido de imagen final se retorna como la representación de la URI. Las dimensiones de imagen y región en píxeles siempre se expresan como números enteros. Los cálculos intermedios pueden emplear números de punto flotante, y el método de redondeo depende de la implementación. Algunos parámetros, en particular, los porcentajes, se pueden especificar con números de punto flotante, los cuales debieran tener, a lo sumo, 10 dígitos decimales, y consistir de dígitos decimales y “.” solamente, con un cero inicial si son menores que 1.0.

4.1. Región

El parámetro región define qué porción rectangular de la imagen completa se retorna. La región se especifica en coordenadas de píxeles, porcentaje, o el valor “full”, que retorna la imagen completa.

Si la petición especifica una región que rebasa las dimensiones reportadas en el documento de información de imagen, el servicio debiera retornar una imagen recortada en el borde de la imagen, no añadir espacio vacío.

Si la altura o ancho de la región solicitada es cero, o si la región está fuera de los límites de las dimensiones reportadas, el servidor debiera retornar un código de estado 400.

Ejemplos:

1 región=full .../full/full/0/default.jpg	2 región=square .../square/full/0/default.jpg
3 región=125,15,120,140 .../125,15,120,140/full/0/default.jpg	4 región=pct:41.6,7.5,40,70 .../pct:41.6,7.5,40,70/full/0/default.jpg
5 región=125,15,200,200 .../125,15,200,200/full/0/default.jpg N.B. La imagen retornada es 175,185 px	6 región=pct:41.6,7.5,66.6,100 .../pct:41.6,7.5,66.6,100/full/0/default.jpg N.B. La imagen retornada es 175,185 px

4.2. Tamaño

El parámetro tamaño determina a qué dimensiones se debe escalar la región extraída.

Si la altura o el ancho resultante es cero, el servidor debiera retornar un código de estado 400 (bad request).

El servidor de imagen puede soportar un escalado que rebase el tamaño de la región extraída.

Alerta de Eliminación La palabra clave de tamaño full será reemplazada por max en la versión 3.0. Sus comentarios son bienvenidos en iiif-discuss o el tema en Github.

Ejemplos:

1 tamaño=full .../full/full/0/default.jpg	1 tamaño=full .../full/max/0/default.jpg N.B. Asumiendo que la imagen tiene maxWidth de 200px	2 tamaño=150, .../full/150,/0/default.jpg
3 tamaño=,150 .../full/,150/0/default.jpg	4 tamaño=pct:50 .../full/pct:50/0/default.jpg	5 tamaño=225,100 .../full/225,100/0/default.jpg
6 tamaño=!225,100 .../full/!225,100/0/default.jpg N.B. La imagen retornada es 150,100 px

4.3. Rotación

El parámetro rotación especifica reflejo y rotación. Un signo de exclamación (“!”) inicial señala que la imagen se debe reflejar sobre el eje vertical antes de aplicar la rotación. El valor numérico indica los grados de rotación en la dirección de las manecillas del reloj, y puede ser cualquier número de punto flotante entre 0 y 360.

Un valor de rotación fuera de rango o no soportado debiera resultar en un código de estado 400.

En la mayoría de los casos, la rotación cambia las dimensiones de ancho y altura de la imagen retornada. El servicio debiera retornar una imagen que incluya todo el contenido de imagen solicitado por los parámetros región y tamaño, incluso si las dimensiones del archivo de imagen retornado son distintas de las especificadas en el parámetro tamaño. El contenido de imagen no debiera ser escalado como resultado de la rotación, y debiera no existir espacio adicional entre las esquinas del contenido de imagen rotado y el recuadro contenedor del contenido de imagen retornado.

Para rotaciones que no sean múltiplos de 90 grados, es recomendado que el cliente solicite la imagen en un formato que soporte la transparencia, por ejemplo, PNG, y que el servidor retorne la imagen con un fondo transparente. La API no incluye una facilidad para que el cliente solicite un color de fondo particular u otro patrón de relleno.

Ejemplos:

1 rotación=0 .../full/full/0/default.jpg	2 rotación=180 .../full/full/180/default.jpg
3 rotación=90 .../full/full/90/default.jpg	4 rotación=22.5 .../full/full/22.5/default.png
5 rotación=!0 .../full/full/!0/default.jpg	6 rotación=!180 .../full/full/!180/default.jpg

4.4. Calidad

El parámetro calidad determina si la imagen se retorna en colores, escala de grises, o blanco y negro.

La calidad default existe para soportar implementaciones compatibles con el nivel 0 que pueden desconocer las calidades de las imágenes individuales de sus colecciones. También es conveniente para clientes que conozcan los valores de todos los parámetros de una petición excepto calidad (por ejemplo, .../full/120,/90/{calidad}.png para solicitar una miniatura) ya que permite omitir una petición preliminar de información de imagen cuyo único fin sería descubrir las calidades disponibles.

Un valor de calidad no soportado debiera producir un código de estado 400.

Ejemplos:

1 calidad=default .../full/full/0/default.jpg	2 calidad=color .../full/full/0/color.jpg
3 calidad=gray .../full/full/0/gray.jpg	4 calidad=bitonal .../full/full/0/bitonal.jpg

4.5. Formato

El formato de la imagen a retornar se expresa como una extensión al final de la URI.

Un valor de formato no soportado debiera producir un código de estado 400.

Ejemplos:

1. .../full/full/0/default.jpg
2. .../full/full/0/default.png
3. .../full/full/0/default.tif

4.6. Orden de Implementación

La secuencia de los parámetros en la URI está pensada como recurso mnemotécnico para el orden en que se deben realizar las manipulaciones de imagen sobre el contenido de imagen. Es una consideración importante al implementar el servicio pues aplicar parámetros iguales en secuencias distintas produce con frecuencia imágenes diferentes. El orden es fundamental para que la aplicación invocadora obtenga fiablemente la salida que espera.

Los parámetros se deben interpretar como si la secuencia de manipulaciones de imagen fuera:

Región ENTONCES Tamaño ENTONCES Rotación ENTONCES Calidad ENTONCES Formato

Si el parámetro rotación incluye reflejo (“!”), el reflejo se aplica antes de la rotación.

1 región=125,15,120,140 tamaño=90, rotación=!345 calidad=gray .../125,15,120,140/90,/!345/gray.jpg

4.7. Sintaxis de URI Canónica

Es posible solicitar la misma imagen usando distintas combinaciones de parámetros. Aunque es útil que los clientes puedan expresar sus peticiones en una forma conveniente, existen varias razones por las cuales una sintaxis de URI canónica es interesante:

• Posibilita implementaciones estáticas, basadas en el sistema de archivos, donde el contenido esté disponible en una URI única.
• El caching es mucho más eficiente, tanto del lado del cliente como del servidor, si se utilizan las mismas URIs entre sistemas y sesiones.
• Mejora los tiempos de respuesta al evitar la redirección a la sintaxis canónica de las peticiones en sintaxis de URI no canónica mediante el uso directo de la forma canónica.

Para soportar los requisitos anteriores, los clientes debieran construir las URIs de petición de imagen usando los valores de parámetro canónicos siguientes, donde sea posible. Los servidores de imagen pueden redirigir a los clientes a la URI canónica desde equivalentes no canónicos.

Cuando el cliente solicita una imagen, el servidor puede añadir un header Link a la respuesta que indique la URI canónica de esa petición:

Link: <http://iiif.example.com/server/full/400,/0/default.jpg>;rel="canonical"

El servidor puede incluir ese header Link en la respuesta de información de imagen, pero no es necesario, ya que está incluído en la representación JSON recuperada.

5. Información de Imagen

Los servidores deben soportar peticiones de información de imagen. La respuesta incluye propiedades técnicas de la imagen y puede contener propiedades de derechos y licencias, y servicios relacionados.

5.1. Petición de Información de Imagen

La petición de información debe cumplir la Plantilla de URI:

{esquema}://{servidor}{/prefijo}/{identificador}/info.json

La sintaxis de respuesta es JSON-LD. El content-type de la respuesta debe ser “application/json” (JSON),

Content-Type: application/json

o “application/ld+json” (JSON-LD).

Content-Type: application/ld+json

Para solicitar explícitamente el content-type JSON-LD, el cliente debe especificarlo en un header Accept; en otro caso, el servidor debe retornar el content-type JSON.

Los servidores debieran enviar el header Access-Control-Allow-Origin con valor * en respuesta a peticiones de información. La sintaxis se muestra a continuación, y está descrita en la especificación CORS. Ese header es requerido para permitir que las respuestas JSON sean empleadas por aplicaciones web alojadas en servidores distintos.

Access-Control-Allow-Origin: *

Las Notas de Implementación de Apache HTTP Server ofrecen una receta para habilitar estos comportamientos.

5.2. Propiedades Técnicas

Los objetos de la lista sizes tienen las propiedades de la tabla siguiente. Las imágenes solicitadas usando esos tamaños debieran tener región “full” y rotación “0”. El tamaño debiera ser solicitado mediante la sintaxis canónica w,. Por tanto, la URL completa de una imagen en calidad “default” y formato “jpg” sería: {esquema}://{servidor}/{prefijo}/{identificador}/full/{ancho},/0/default.jpg

Alerta Existe una incoherencia entre la especificación de la lista sizes y la sintaxis de URI canónica. Los clientes debieran utilizar la Sintaxis de URI Canónica al hacer peticiones de imagen basadas en entradas de sizes. Para la máxima compatibilidad, los servidores debieran soportar las formas w, y w,h del parámetro tamaño para valores de sizes que preserven la relación de aspecto. La incoherencia será resuelta en la próxima versión mayor de esta especificación.

Los objetos de la lista tiles tienen las propiedades de la tabla siguiente. width y height debieran ser usadas en el parámetro región, y scaleFactors en el parámetro tamaño de la URL de la imagen. Esto se describe en detalle en las Notas de Implementación.

width, o la combinación de width y height, si height se especifica, debe ser única para cada miembro de la lista tiles.

Los servidores debieran soportar las peticiones de imágenes con parámetros especificados por los campos sizes y tiles para todas las combinaciones de calidades y formatos soportadas.

La siguiente es una respuesta de información de imagen válida, que incluye las propiedades opcionales sizes y tiles.

{
  "@context" : "http://iiif.io/api/image/2/context.json",
  "@id" : "http://www.example.org/image-service/abcd1234/1E34750D-38DB-4825-A38A-B60A345E591C",
  "protocol" : "http://iiif.io/api/image",
  "width" : 6000,
  "height" : 4000,
  "sizes" : [
    {"width" : 150, "height" : 100},
    {"width" : 600, "height" : 400},
    {"width" : 3000, "height": 2000}
  ],
  "tiles": [
    {"width" : 512, "scaleFactors" : [1,2,4,8,16]}
  ],
  "profile" : [ "http://iiif.io/api/image/2/level2.json" ]
}

5.3. Descripción de Perfil

Para especificar características adicionales soportadas por la imagen, es posible añadir un objeto de perfil a la lista profile. Los objetos de la lista profile tienen las propiedades de la tabla siguiente. Las propiedades @context, @id y @type son requeridas si el perfil es desreferenciado desde una URI, pero no debieran ser incluídas en la respuesta de información de imagen.

Los parámetros maxWidth, maxHeight y maxArea ofrecen un medio para que los servidores de imagen expresen límites sobre los tamaños soportados para la imagen. Si sólo maxWidth, o maxWidth y maxHeight son especificados, los clientes debieran esperar que las peticiones de dimensiones lineales mayores sean rechazadas. Si se especifica maxArea, los clientes debieran esperar que las peticiones de áreas en píxeles mayores sean rechazadas. Los parámetros maxWidth / maxHeight y maxArea son independientes; los servidores pueden implementar cualquiera de los dos límites, o ambos. Los servidores deben garantizar que los tamaños especificados por las propiedades sizes o tiles estén dentro de los límites de tamaño expresados. Los clientes no debieran hacer peticiones que excedan los límites de tamaño expresados.

El conjunto de características que se pueden especificar en la propiedad supports de un ImageProfile es:

Alerta de Eliminación Las características sizeByWhListed y sizeByForcedWh son obsoletas, y se eliminarán en la versión 3.0. sizeByForcedWh se definió incoherentemente en la versión 2.0, y sizeByWhListed queda implícita al expresar los tamaños en el documento de información de imagen y, por tanto, no es requerida como característica nombrada.

Las características sizeByWh y sizeByDistortedWh comparten la sintaxis “w,h” para el parámetro tamaño, pero representan características distintas. Un servidor que soporte sizeByWh, pero no sizeByDistortedWh, servirá una respuesta de imagen en cualquier escala (sujeta a restricciones individuales maxWidth, maxHeight, maxArea y sizeAboveFull, de estar presentes), pero sólo si la imagen resultante preserva la relación de aspecto original; las peticiones de imágenes distorsionadas no serán servidas.

Un servidor que no soporte sizeByW ni sizeByWh sólo está obligado a servir los tamaños de imagen expresados en la propiedad sizes, o implicados por la propiedad tiles del documento de información de imagen, lo cual permite una implementación de archivo estático.

El conjunto de características, formatos y calidades soportadas es la unión de las declaradas en documentos de perfil externos, y en objetos de perfil incrustados. Si una característica no está presente en el documento de perfil, o la propiedad supports de un perfil incrustado, un cliente debe asumir que la característica no es soportada.

Si formats, qualities, o supports carece de valores adicionales distintos de los especificados en el nivel de cumplimiento referenciado, la propiedad debiera ser omitida de la respuesta, y no estar presente con una lista vacía.

Se pueden añadir URIs a la lista supports de un perfil para cubrir características no definidas en esta especificación. Los clientes deben ignorar las URIs no reconocidas.

El perfil siguiente indica soporte de formatos, calidades, y características adicionales al cumplimiento de nivel 2. También incluye un límite de tamaño.

{
  "@context" : "http://iiif.io/api/image/2/context.json",
  "@id" : "http://www.example.org/image-service/abcd1234/1E34750D-38DB-4825-A38A-B60A345E591C",
  "protocol" : "http://iiif.io/api/image",
  //...
  "profile" : [
    "http://iiif.io/api/image/2/level2.json",
    {
      "formats" : [ "gif", "pdf" ],
      "qualities" : [ "color", "gray" ],
      "maxWidth" : 2000,
      "supports" : [
          "canonicalLinkHeader", "rotationArbitrary", "profileLinkHeader", "http://example.com/feature/"
      ]
    }
  ]
}

5.4. Propiedades de Derechos y Licencias

Las propiedades de derechos y licencias, attribution, license y logo, poseen iguales semántica y requisitos que las presentes en la API de Presentación.

Las propiedades de derechos y licencias pueden tener múltiples valores, expresados como un array JSON, o un valor único.

Cuando se proporcionan múltiples valores de attribution, los clientes deben usar el siguiente algoritmo para determinar cuales valores mostrar al usuario.

• Si ningún valor tiene asociado un idioma, el cliente debe mostrar todos los valores.
• En otro caso, el cliente debiera intentar determinar la preferencia de idioma del usuario o, si no es posible, utilizar alguna preferencia de idioma predeterminada. Entonces:
  • Si algún valor tiene asociado un idioma, el cliente debe mostrar todos los valores asociados al idioma que mejor corresponda a la preferencia de idioma.
  • Si todo valor tiene asociado un idioma, y ninguno corresponde a la preferencia de idioma, el cliente debe seleccionar un idioma y mostrar todos los valores asociados a ese idioma.
  • Si algunos valores tienen idiomas asociados, pero ninguno corresponde a la preferencia de idioma, el cliente debe mostrar todo valor que no tenga un idioma asociado.

El valor de la propiedad logo puede ser un string con la URL de la imagen, o un objeto JSON que especifique las URIs de la imagen del logo y de un servicio de la API de Imagen de IIIF para el logo. Aunque posible, es recomendado que los logos con servicios IIIF no posean, a su vez, logos. Los clientes que encuentren logos con logos no están obligados a mostrar un conjunto potencialmente infinito.

Si las APIs de Imagen y Presentación expresan attributions y logos simultáneamente, los clientes deben presentar ambas, a menos que sean idénticas.

Seguidamente, un uso sencillo de estas propiedades:

{
  "@context" : "http://iiif.io/api/image/2/context.json",
  "@id" : "http://www.example.org/image-service/abcd1234/1E34750D-38DB-4825-A38A-B60A345E591C",
  "protocol" : "http://iiif.io/api/image",
  // ...
  "attribution" : "Provisto por la Organización Ejemplo",
  "logo" : "http://example.org/images/logo.png",
  "license" : "http://example.org/rights/license1.html"
  // ...
}

Ejemplos más complejos se ofrecen en el ejemplo de Respuesta Completa.

5.5. Servicios Relacionados

puede haber uno o más servicios asociados a una imagen. Vea el anexo Perfiles de Servicio para más información.

Seguidamente, un uso de service para asociar la página de inicio de sesión de un sistema de autenticación por el cual deben pasar los usuarios para acceder a la imagen. Para más información, vea Autenticación.

{
  "@context" : "http://iiif.io/api/image/2/context.json",
  "@id" : "http://www.example.org/image-service/abcd1234/1E34750D-38DB-4825-A38A-B60A345E591C",
  "protocol" : "http://iiif.io/api/image",
  // ...
  "service": {
    "@context" : "http://iiif.io/api/auth/1/context.json",
    "@id" : "http://www.example.org/auth/login.html",
    "profile": "http://iiif.io/api/auth/1/login"
  }
}

Ejemplos más complejos se ofrecen en el ejemplo de Respuesta Completa.

5.6. Respuesta Completa

La siguiente respuesta incluye todas las propiedades de información de imagen requeridas y opcionales.

{
  "@context" : "http://iiif.io/api/image/2/context.json",
  "@id" : "http://www.example.org/image-service/abcd1234/1E34750D-38DB-4825-A38A-B60A345E591C",
  "protocol" : "http://iiif.io/api/image",
  "width" : 6000,
  "height" : 4000,
  "sizes" : [
    {"width" : 150, "height" : 100},
    {"width" : 600, "height" : 400},
    {"width" : 3000, "height": 2000}
  ],
  "tiles": [
    {"width" : 512, "scaleFactors" : [1,2,4]},
    {"width" : 1024, "height" : 2048, "scaleFactors" : [8,16]}
  ],
  "attribution" : [
    {
      "@value" : "<span>Provisto por la Organización Ejemplo</span>",
      "@language" : "en"
    },{
      "@value" : "<span>Darparwyd gan Enghraifft Sefydliad</span>",
      "@language" : "cy"
    }
  ],
  "logo" : {
      "@id" : "http://example.org/image-service/logo/full/200,/0/default.png",
      "service" : {
        "@context" : "http://iiif.io/api/image/2/context.json",
        "@id" : "http://example.org/image-service/logo",
        "profile" : "http://iiif.io/api/image/2/level2.json"
      }
  },
  "license" : [
    "http://example.org/rights/license1.html",
    "https://creativecommons.org/licenses/by/4.0/"
  ],
  "profile" : [
    "http://iiif.io/api/image/2/level2.json",
    {
      "formats" : [ "gif", "pdf" ],
      "qualities" : [ "color", "gray" ],
      "supports" : [
        "canonicalLinkHeader", "rotationArbitrary", "profileLinkHeader", "http://example.com/feature/"
      ]
    }
  ],
  "service" : [
    {
      "@context": "http://iiif.io/api/annex/service/physdim/1/context.json",
      "profile": "http://iiif.io/api/annex/service/physdim",
      "physicalScale": 0.0025,
      "physicalUnits": "in"
    },{
      "@context" : "http://geojson.org/contexts/geojson-base.jsonld",
      "@id" : "http://www.example.org/geojson/paris.json"
    }
  ]
}

6. Niveles de Cumplimiento

El documento de información de imagen debe especificar hasta qué punto se soporta la API mediante la inclusión de una URI de nivel de cumplimiento como primera entrada de la propiedad profile. Esa URI enlaza con la descripción del mayor nivel de cumplimiento para el cual se satisfagan todos los requisitos. La URI debe ser una de las mencionadas en el documento Cumplimiento de la API de Imagen. La descripción contiene el conjunto de características requeridas por el perfil, como se explicó en la sección Información de Imagen. Un servidor puede declarar niveles de cumplimiento distintos para imágenes con identificadores diferentes.

La URI de nivel de cumplimiento también puede ser expresada en el header HTTP Link (RFC5988) mediante el parámetro rel="profile"; por tanto, un header completo podría ser:

Link: <http://iiif.io/api/image/2/level1.json>;rel="profile"

Las Notas de Implementación de Apache HTTP Server incluyen una receta para especificar ese header en Apache HTTP Server.

7. Respuestas de Servidor

7.1. Respuestas Exitosas

Los servidores pueden transmitir respuestas HTTP con códigos de estado 200 (Successful) o 3xx (Redirect) si la petición fue procesada exitosamente. Si el código de estado es 200, entity-body debe ser la imagen o documento de información solicitados. Si el código de estado es 301, 302, 303, o 304, entity-body no tiene restricciones, pero es recomendado que sea vacío. Si el código de estado es 301, 302, o 303, el header HTTP Location se debe especificar con la URI de la imagen que satisface la petición. Eso permite que los servidores tengan una URI canónica y promuevan el caching de las respuestas. El código de estado 304 se maneja exactamente como indica la especificación HTTP. Los clientes debieran esperar todas esas situaciones, y no deben asumir que el entity-body de la respuesta inicial contiene los datos de imagen.

7.2. Condiciones de Error

El orden en que los servidores parsean peticiones y detectan errores no es especificado. Es probable que una petición falle al encontrar el primer error, y retorne un código de estado HTTP adecuado; los códigos comunes están en la lista siguiente. Es recomendado que el cuerpo de la respuesta de error incluya una descripción del error, legible por humanos, en texto plano o html.

8. Autenticación

Las imágenes suelen ser recursos secundarios en una página web o aplicación. En el caso de las páginas web, las imágenes se incrustan en la etiqueta HTML img, y se recuperan mediante peticiones HTTP adicionales. Si un usuario no puede cargar una página web, es posible (y un comportamiento aceptado en general) redirigir al usuario a otra página, y ofrecer la oportunidad de autenticar. Esa opción no es para recursos secundarios, como las imágenes, y en su lugar se muestra al usuario un ícono de imagen rota.

No proponemos nuevos mecanismos de autenticación, ni roles para la lógica de autorización. Esperamos que los requisitos y procesos de autenticación se manejen fuera de contextos específicos de IIIF, pero dentro de un flujo de trabajo de control de acceso compatible con IIIF. Por favor, vea la especificación sobre autenticación.

9. Codificación y Decodificación de URI

La sintaxis de URI de esta API se apoya en separadores slash (/) que no deben ser codificados. Los clientes deben codificar con porciento los caracteres especiales (el conjunto a-codificar siguiente: porciento y delimitadores generales de RFC3986 excepto dos puntos) y cualquier carácter ajeno al conjunto US-ASCII que sea parte de los componentes de las peticiones. Por ejemplo, los slashes en el componente identificador de la URI se deben codificar con porciento. La codificación es necesaria sólo en el identificador pues los restantes componentes no incluirán caracteres especiales. Codificar con porciento otros caracteres no crea ambigüedad pero es innecesario.

a-codificar = "/" / "?" / "#" / "[" / "]" / "@" / "%"

Los servidores que no puedan procesar identificadores codificados arbitrariamente debieran hacer todo lo posible para exponer sólo identificadores de imagen para los cuales los clientes no deban codificar ningún carácter; por tanto, es recomendado limitar los caracteres de los identificadores a letras, números y _.

10. Consideraciones de Seguridad

Esta API define una sintaxis de URI, y la semántica asociada a sus componentes. La composición de URIs presenta pocos riesgos de seguridad, fuera de la posible revelación de información sensible en las URIs, o de comportamientos de navegación/visualización de los usuarios.

Las aplicaciones de servidor que implementen esta API debieran contemplar ataques DoS, y vulnerabilidades de autenticación basadas en spoofing de DNS. Las aplicaciones deben parsear e higienizar las peticiones (URIs) entrantes a fin de evitar ataques de inyección, desbordamiento, y recorrido de directorio.

Es recomendado que los servidores que incluyan la característica sizeAboveFull implementen también una o más de maxWidth, maxHeight, o maxArea para impedir peticiones de imagen arbitrariamente grandes que expongan el servidor a ataques DoS.

Es recomendada la verificación temprana de la sanidad de las URIs (longitudes, GET final, caracteres inválidos, parámetros fuera-de-rango) y el rechazo con códigos de respuesta apropiados.

11. Apéndices

A. Notas de Implementación

• Para casos de uso que habiliten el guardado de la imagen, es recomendado usar el header HTTP Content-Disposition (RFC6266) para ofrecer un nombre de archivo conveniente, que distinga la imagen, basado en el identificador y los parámetros provistos.
• Las implementaciones de servidor pueden estar apoyadas en componentes o marcos de trabajo que eliminen los escapes en la ruta de URI, por ejemplo, WSGI de Python. En tales situaciones, la URI solicitada se puede parsear por la derecha a fin de manejar identificadores que puedan contener slashes, dado el conocimiento de los parámetros de la API, y el prefijo para el cual el servidor maneja peticiones.
• Esta especificación no afirma nada sobre el estado de los derechos de las imágenes solicitadas o cualquier otro metadato descriptivo, con o sin autenticación exitosa. Por favor, vea la API de Presentación de IIIF para los derechos y otra información.
• Están disponibles notas de implementación de Apache HTTP Server adicionales.
• Las implementaciones de datos enlazados pueden construir la respuesta info.json usando el frame suministrado en la nota de implementación de framing de JSON-LD.
• Al solicitar tamaños usando la sintaxis canónica w,, para obtener una altura particular, es posible usar el siguiente algoritmo:

    # Calcular el ancho a solicitar con la sintaxis `w,` a partir de la altura deseada
    ancho_petición = ancho_imagen * altura_deseada / altura_imagen

• Al solicitar mosaicos de imagen, se deben calcular los parámetros Región y Tamaño para contemplar mosaicos parciales a lo largo de los bordes derecho e inferior de una imagen completa que no sea múltiplo exacto del tamaño de mosaico escalado. El siguiente algoritmo está expresado como código Python, y asume entradas enteras y aritmética entera todo el tiempo (o sea, descarta el resto de la división). Las entradas son: tamaño del contenido de imagen (ancho,altura), factor de escala s, tamaño de mosaico (tw,th), y coordenada de mosaico (n,m) contando desde (0,0) en la esquina superior izquierda. Note que el método de redondeo depende de la implementación.

    # Calcular parámetro región /xr,yr,wr,hr/
    xr = n * tw * s
    yr = m * th * s
    wr = tw * s
    if (xr + wr > ancho):
        wr = ancho - xr
    hr = th * s
    if (yr + hr > altura):
        hr = altura - yr
    # Calcular parámetro tamaño /ws,hs/
    ws = tw
    if (xr + tw*s > ancho):
        ws = (ancho - xr + s - 1) / s  # +s-1 en el numerador para redondear
    hs = th
    if (yr + th*s > altura):
        hs = (altura - yr + s - 1) / s

• Como se describió en Rotación, para retener el tamaño del contenido de imagen solicitado, la rotación cambia las dimensiones de ancho y altura de la imagen retornada. A continuación, una fórmula para calcular las dimensiones de la imagen retornada, con un tamaño inicial y rotación dados. Note que el método de redondeo depende de la implementación, y que ciertos lenguajes requieren convertir el ángulo de grados a radianes.

    # (w,h) es el parámetro tamaño, n es el ángulo de rotación
    w_retornado = abs(w*cos(n)) + abs(h*sin(n))
    h_retornada = abs(h*cos(n)) + abs(w*sin(n))

B. Control de Versiones

A partir de la versión 2.0, esta especificación sigue Semantic Versioning. Vea la nota Control de Versiones de APIs para los detalles de implementación.

C. Agradecimientos

La producción de este documento fue apoyada generosamente por una donación de la Fundación Andrew W. Mellon.

Muchas gracias a los miembros del IIIF por su continuo compromiso, ideas innovadoras y retroalimentación.

D. Registro de Cambios